
<!DOCTYPE html>

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta charset="utf-8" />
    <title>Introduction to atomman: table conversions &#8212; atomman 1.4.0 documentation</title>
    <link rel="stylesheet" href="../_static/basic.css" type="text/css" />
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
    <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
    <script type="text/javascript" src="../_static/jquery.js"></script>
    <script type="text/javascript" src="../_static/underscore.js"></script>
    <script type="text/javascript" src="../_static/doctools.js"></script>
    <script type="text/javascript" src="../_static/language_data.js"></script>
    <script crossorigin="anonymous" integrity="sha256-Ae2Vz/4ePdIu6ZyI/5ZGsYnb+m0JlOmKPjt6XZ9JJkA=" type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js"></script>
    <script async="async" type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/latest.js?config=TeX-AMS-MML_HTMLorMML"></script>
    <script type="text/x-mathjax-config">MathJax.Hub.Config({"tex2jax": {"inlineMath": [["$", "$"], ["\\(", "\\)"]], "processEscapes": true, "ignoreClass": "document", "processClass": "math|output_area"}})</script>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="Introduction to atomman: LAMMPS data file conversions" href="1.4.5._LAMMPS_data_file_conversions.html" />
    <link rel="prev" title="Introduction to atomman: CIF conversions" href="1.4.3._CIF_conversions.html" /> 
  </head><body>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="../genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="../py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="1.4.5._LAMMPS_data_file_conversions.html" title="Introduction to atomman: LAMMPS data file conversions"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="1.4.3._CIF_conversions.html" title="Introduction to atomman: CIF conversions"
             accesskey="P">previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="../index.html">atomman 1.4.0 documentation</a> &#187;</li>
          <li class="nav-item nav-item-1"><a href="index.html" accesskey="U">Tutorials</a> &#187;</li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  
<style>
/* CSS for nbsphinx extension */

/* remove conflicting styling from Sphinx themes */
div.nbinput.container div.prompt *,
div.nboutput.container div.prompt *,
div.nbinput.container div.input_area pre,
div.nboutput.container div.output_area pre,
div.nbinput.container div.input_area .highlight,
div.nboutput.container div.output_area .highlight {
    border: none;
    padding: 0;
    margin: 0;
    box-shadow: none;
}

div.nbinput.container > div[class*=highlight],
div.nboutput.container > div[class*=highlight] {
    margin: 0;
}

div.nbinput.container div.prompt *,
div.nboutput.container div.prompt * {
    background: none;
}

div.nboutput.container div.output_area .highlight,
div.nboutput.container div.output_area pre {
    background: unset;
}

div.nboutput.container div.output_area div.highlight {
    color: unset;  /* override Pygments text color */
}

/* avoid gaps between output lines */
div.nboutput.container div[class*=highlight] pre {
    line-height: normal;
}

/* input/output containers */
div.nbinput.container,
div.nboutput.container {
    display: -webkit-flex;
    display: flex;
    align-items: flex-start;
    margin: 0;
    width: 100%;
}
@media (max-width: 540px) {
    div.nbinput.container,
    div.nboutput.container {
        flex-direction: column;
    }
}

/* input container */
div.nbinput.container {
    padding-top: 5px;
}

/* last container */
div.nblast.container {
    padding-bottom: 5px;
}

/* input prompt */
div.nbinput.container div.prompt pre {
    color: #307FC1;
}

/* output prompt */
div.nboutput.container div.prompt pre {
    color: #BF5B3D;
}

/* all prompts */
div.nbinput.container div.prompt,
div.nboutput.container div.prompt {
    width: 4.5ex;
    padding-top: 5px;
    position: relative;
    user-select: none;
}

div.nbinput.container div.prompt > div,
div.nboutput.container div.prompt > div {
    position: absolute;
    right: 0;
    margin-right: 0.3ex;
}

@media (max-width: 540px) {
    div.nbinput.container div.prompt,
    div.nboutput.container div.prompt {
        width: unset;
        text-align: left;
        padding: 0.4em;
    }
    div.nboutput.container div.prompt.empty {
        padding: 0;
    }

    div.nbinput.container div.prompt > div,
    div.nboutput.container div.prompt > div {
        position: unset;
    }
}

/* disable scrollbars on prompts */
div.nbinput.container div.prompt pre,
div.nboutput.container div.prompt pre {
    overflow: hidden;
}

/* input/output area */
div.nbinput.container div.input_area,
div.nboutput.container div.output_area {
    -webkit-flex: 1;
    flex: 1;
    overflow: auto;
}
@media (max-width: 540px) {
    div.nbinput.container div.input_area,
    div.nboutput.container div.output_area {
        width: 100%;
    }
}

/* input area */
div.nbinput.container div.input_area {
    border: 1px solid #e0e0e0;
    border-radius: 2px;
    /*background: #f5f5f5;*/
}

/* override MathJax center alignment in output cells */
div.nboutput.container div[class*=MathJax] {
    text-align: left !important;
}

/* override sphinx.ext.imgmath center alignment in output cells */
div.nboutput.container div.math p {
    text-align: left;
}

/* standard error */
div.nboutput.container div.output_area.stderr {
    background: #fdd;
}

/* ANSI colors */
.ansi-black-fg { color: #3E424D; }
.ansi-black-bg { background-color: #3E424D; }
.ansi-black-intense-fg { color: #282C36; }
.ansi-black-intense-bg { background-color: #282C36; }
.ansi-red-fg { color: #E75C58; }
.ansi-red-bg { background-color: #E75C58; }
.ansi-red-intense-fg { color: #B22B31; }
.ansi-red-intense-bg { background-color: #B22B31; }
.ansi-green-fg { color: #00A250; }
.ansi-green-bg { background-color: #00A250; }
.ansi-green-intense-fg { color: #007427; }
.ansi-green-intense-bg { background-color: #007427; }
.ansi-yellow-fg { color: #DDB62B; }
.ansi-yellow-bg { background-color: #DDB62B; }
.ansi-yellow-intense-fg { color: #B27D12; }
.ansi-yellow-intense-bg { background-color: #B27D12; }
.ansi-blue-fg { color: #208FFB; }
.ansi-blue-bg { background-color: #208FFB; }
.ansi-blue-intense-fg { color: #0065CA; }
.ansi-blue-intense-bg { background-color: #0065CA; }
.ansi-magenta-fg { color: #D160C4; }
.ansi-magenta-bg { background-color: #D160C4; }
.ansi-magenta-intense-fg { color: #A03196; }
.ansi-magenta-intense-bg { background-color: #A03196; }
.ansi-cyan-fg { color: #60C6C8; }
.ansi-cyan-bg { background-color: #60C6C8; }
.ansi-cyan-intense-fg { color: #258F8F; }
.ansi-cyan-intense-bg { background-color: #258F8F; }
.ansi-white-fg { color: #C5C1B4; }
.ansi-white-bg { background-color: #C5C1B4; }
.ansi-white-intense-fg { color: #A1A6B2; }
.ansi-white-intense-bg { background-color: #A1A6B2; }

.ansi-default-inverse-fg { color: #FFFFFF; }
.ansi-default-inverse-bg { background-color: #000000; }

.ansi-bold { font-weight: bold; }
.ansi-underline { text-decoration: underline; }


div.nbinput.container div.input_area div[class*=highlight] > pre,
div.nboutput.container div.output_area div[class*=highlight] > pre,
div.nboutput.container div.output_area div[class*=highlight].math,
div.nboutput.container div.output_area.rendered_html,
div.nboutput.container div.output_area > div.output_javascript,
div.nboutput.container div.output_area:not(.rendered_html) > img{
    padding: 5px;
    margin: 0;
}

/* fix copybtn overflow problem in chromium (needed for 'sphinx_copybutton') */
div.nbinput.container div.input_area > div[class^='highlight'],
div.nboutput.container div.output_area > div[class^='highlight']{
    overflow-y: hidden;
}

/* hide copybtn icon on prompts (needed for 'sphinx_copybutton') */
.prompt a.copybtn {
    display: none;
}

/* Some additional styling taken form the Jupyter notebook CSS */
div.rendered_html table {
  border: none;
  border-collapse: collapse;
  border-spacing: 0;
  color: black;
  font-size: 12px;
  table-layout: fixed;
}
div.rendered_html thead {
  border-bottom: 1px solid black;
  vertical-align: bottom;
}
div.rendered_html tr,
div.rendered_html th,
div.rendered_html td {
  text-align: right;
  vertical-align: middle;
  padding: 0.5em 0.5em;
  line-height: normal;
  white-space: normal;
  max-width: none;
  border: none;
}
div.rendered_html th {
  font-weight: bold;
}
div.rendered_html tbody tr:nth-child(odd) {
  background: #f5f5f5;
}
div.rendered_html tbody tr:hover {
  background: rgba(66, 165, 245, 0.2);
}
</style>
<div class="section" id="Introduction-to-atomman:-table-conversions">
<h1>Introduction to atomman: table conversions<a class="headerlink" href="#Introduction-to-atomman:-table-conversions" title="Permalink to this headline">¶</a></h1>
<p><strong>Lucas M. Hale</strong>, <a class="reference external" href="mailto:lucas&#46;hale&#37;&#52;&#48;nist&#46;gov?Subject=ipr-demo">lucas<span>&#46;</span>hale<span>&#64;</span>nist<span>&#46;</span>gov</a>, <em>Materials Science and Engineering Division, NIST</em>.</p>
<p><a class="reference external" href="http://www.nist.gov/public_affairs/disclaimer.cfm">Disclaimers</a></p>
<div class="section" id="1.-Introduction">
<h2>1. Introduction<a class="headerlink" href="#1.-Introduction" title="Permalink to this headline">¶</a></h2>
<p>Atomic configuration data is often expressed in a tabular form as it is an efficient way of representing per-atom properties. Many commn formats, such as the xyz format, are little more than this. In atomman, the table load/dump style provides a means of converting to/from a generic table format. As such, the table-style converter can be used to help with defining converters from more specific tabular formats.</p>
<p><strong>Library Imports</strong></p>
<div class="nbinput docutils container">
<div class="prompt highlight-none notranslate"><div class="highlight"><pre><span></span>[1]:
</pre></div>
</div>
<div class="input_area highlight-ipython3 notranslate"><div class="highlight"><pre>
<span></span><span class="c1"># Standard Python libraries</span>
<span class="kn">import</span> <span class="nn">datetime</span>

<span class="c1"># http://www.numpy.org/</span>
<span class="kn">import</span> <span class="nn">numpy</span> <span class="k">as</span> <span class="nn">np</span>

<span class="kn">import</span> <span class="nn">atomman</span> <span class="k">as</span> <span class="nn">am</span>
<span class="kn">import</span> <span class="nn">atomman.unitconvert</span> <span class="k">as</span> <span class="nn">uc</span>

<span class="c1"># Show atomman version</span>
<span class="nb">print</span><span class="p">(</span><span class="s1">&#39;atomman version =&#39;</span><span class="p">,</span> <span class="n">am</span><span class="o">.</span><span class="n">__version__</span><span class="p">)</span>

<span class="c1"># Show date of Notebook execution</span>
<span class="nb">print</span><span class="p">(</span><span class="s1">&#39;Notebook executed on&#39;</span><span class="p">,</span> <span class="n">datetime</span><span class="o">.</span><span class="n">date</span><span class="o">.</span><span class="n">today</span><span class="p">())</span>
</pre></div>
</div>
</div>
<div class="nboutput nblast docutils container">
<div class="prompt empty docutils container">
</div>
<div class="output_area docutils container">
<div class="highlight"><pre>
atomman version = 1.4.0
Notebook executed on 2021-08-04
</pre></div></div>
</div>
<p>Generate test system information (CsCl)</p>
<div class="nbinput docutils container">
<div class="prompt highlight-none notranslate"><div class="highlight"><pre><span></span>[2]:
</pre></div>
</div>
<div class="input_area highlight-ipython3 notranslate"><div class="highlight"><pre>
<span></span><span class="c1"># Generate box</span>
<span class="n">alat</span> <span class="o">=</span> <span class="n">uc</span><span class="o">.</span><span class="n">set_in_units</span><span class="p">(</span><span class="mf">3.2</span><span class="p">,</span> <span class="s1">&#39;angstrom&#39;</span><span class="p">)</span>
<span class="n">box</span> <span class="o">=</span> <span class="n">am</span><span class="o">.</span><span class="n">Box</span><span class="p">(</span><span class="n">a</span><span class="o">=</span><span class="n">alat</span><span class="p">,</span> <span class="n">b</span><span class="o">=</span><span class="n">alat</span><span class="p">,</span> <span class="n">c</span><span class="o">=</span><span class="n">alat</span><span class="p">)</span>

<span class="c1"># Generate atoms with atype, pos, charge, and stress properties</span>
<span class="n">atype</span> <span class="o">=</span> <span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">]</span>
<span class="n">pos</span> <span class="o">=</span> <span class="p">[[</span><span class="mi">0</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">0</span><span class="p">],</span> <span class="p">[</span><span class="mf">0.5</span><span class="p">,</span> <span class="mf">0.5</span><span class="p">,</span> <span class="mf">0.5</span><span class="p">]]</span>
<span class="n">charge</span> <span class="o">=</span> <span class="n">uc</span><span class="o">.</span><span class="n">set_in_units</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="o">-</span><span class="mi">1</span><span class="p">],</span> <span class="s1">&#39;e&#39;</span><span class="p">)</span>
<span class="n">stress</span> <span class="o">=</span> <span class="n">uc</span><span class="o">.</span><span class="n">set_in_units</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">zeros</span><span class="p">((</span><span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">3</span><span class="p">)),</span> <span class="s1">&#39;MPa&#39;</span><span class="p">)</span>
<span class="n">atoms</span> <span class="o">=</span> <span class="n">am</span><span class="o">.</span><span class="n">Atoms</span><span class="p">(</span><span class="n">pos</span><span class="o">=</span><span class="n">pos</span><span class="p">,</span> <span class="n">atype</span><span class="o">=</span><span class="n">atype</span><span class="p">,</span> <span class="n">charge</span><span class="o">=</span><span class="n">charge</span><span class="p">,</span> <span class="n">stress</span><span class="o">=</span><span class="n">stress</span><span class="p">)</span>

<span class="c1"># Build system from box and atoms, and scale atoms</span>
<span class="n">system</span> <span class="o">=</span> <span class="n">am</span><span class="o">.</span><span class="n">System</span><span class="p">(</span><span class="n">atoms</span><span class="o">=</span><span class="n">atoms</span><span class="p">,</span> <span class="n">box</span><span class="o">=</span><span class="n">box</span><span class="p">,</span> <span class="n">scale</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">symbols</span><span class="o">=</span><span class="p">[</span><span class="s1">&#39;Cs&#39;</span><span class="p">,</span> <span class="s1">&#39;Cl&#39;</span><span class="p">])</span>

<span class="c1"># Print system information</span>
<span class="nb">print</span><span class="p">(</span><span class="n">system</span><span class="p">)</span>
<span class="n">system</span><span class="o">.</span><span class="n">atoms_df</span><span class="p">()</span>
</pre></div>
</div>
</div>
<div class="nboutput docutils container">
<div class="prompt empty docutils container">
</div>
<div class="output_area docutils container">
<div class="highlight"><pre>
avect =  [ 3.200,  0.000,  0.000]
bvect =  [ 0.000,  3.200,  0.000]
cvect =  [ 0.000,  0.000,  3.200]
origin = [ 0.000,  0.000,  0.000]
natoms = 2
natypes = 2
symbols = (&#39;Cs&#39;, &#39;Cl&#39;)
pbc = [ True  True  True]
per-atom properties = [&#39;atype&#39;, &#39;pos&#39;, &#39;charge&#39;, &#39;stress&#39;]
     id |   atype |  pos[0] |  pos[1] |  pos[2]
      0 |       1 |   0.000 |   0.000 |   0.000
      1 |       2 |   1.600 |   1.600 |   1.600
</pre></div></div>
</div>
<div class="nboutput nblast docutils container">
<div class="prompt highlight-none notranslate"><div class="highlight"><pre><span></span>[2]:
</pre></div>
</div>
<div class="output_area rendered_html docutils container">
<div>
<style scoped>
    .dataframe tbody tr th:only-of-type {
        vertical-align: middle;
    }

    .dataframe tbody tr th {
        vertical-align: top;
    }

    .dataframe thead th {
        text-align: right;
    }
</style>
<table border="1" class="dataframe">
  <thead>
    <tr style="text-align: right;">
      <th></th>
      <th>atype</th>
      <th>pos[0]</th>
      <th>pos[1]</th>
      <th>pos[2]</th>
      <th>charge</th>
      <th>stress[0][0]</th>
      <th>stress[0][1]</th>
      <th>stress[0][2]</th>
      <th>stress[1][0]</th>
      <th>stress[1][1]</th>
      <th>stress[1][2]</th>
      <th>stress[2][0]</th>
      <th>stress[2][1]</th>
      <th>stress[2][2]</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>0</td>
      <td>1</td>
      <td>0.0</td>
      <td>0.0</td>
      <td>0.0</td>
      <td>1.0</td>
      <td>0.0</td>
      <td>0.0</td>
      <td>0.0</td>
      <td>0.0</td>
      <td>0.0</td>
      <td>0.0</td>
      <td>0.0</td>
      <td>0.0</td>
      <td>0.0</td>
    </tr>
    <tr>
      <td>1</td>
      <td>2</td>
      <td>1.6</td>
      <td>1.6</td>
      <td>1.6</td>
      <td>-1.0</td>
      <td>0.0</td>
      <td>0.0</td>
      <td>0.0</td>
      <td>0.0</td>
      <td>0.0</td>
      <td>0.0</td>
      <td>0.0</td>
      <td>0.0</td>
      <td>0.0</td>
    </tr>
  </tbody>
</table>
</div></div>
</div>
</div>
<div class="section" id="2.-System.dump(‘table’)">
<h2>2. System.dump(‘table’)<a class="headerlink" href="#2.-System.dump(‘table’)" title="Permalink to this headline">¶</a></h2>
<p>Parameters</p>
<ul class="simple">
<li><p><strong>f</strong> (<em>str or file-like object, optional</em>) File path or file-like object to write the table to. If not given, then the table is returned as a string.</p></li>
<li><p><strong>prop_name</strong> (<em>list, optional</em>) The Atoms properties to include. Must be given if prop_info is not.</p></li>
<li><p><strong>table_name</strong> (<em>list, optional</em>) The table column name(s) that correspond to each prop_name. If not given, the table_name values will be based on the prop_name values.</p></li>
<li><p><strong>shape</strong> (<em>list, optional</em>) The shape of each per-atom property. If not given, will be inferred from the length of each table_name value.</p></li>
<li><p><strong>unit</strong> (<em>list, optional</em>) Lists the units for each prop_name as stored in the table. For a value of None, no conversion will be performed for that property. For a value of ‘scaled’, the corresponding table values will be taken in box-scaled units. If not given, all unit values will be set to None (i.e. no conversions).</p></li>
<li><p><strong>dtype</strong> (<em>list, optional</em>) Allows for the data type of each property to be explicitly given. Values of None will infer the data type from the corresponding property values. If not given, all values will be None.</p></li>
<li><p><strong>prop_info</strong> (<em>list of dict, optional</em>) Structured form of property conversion parameters, in which each dictionary in the list corresponds to a single atoms property. Each dictionary must have a ‘prop_name’ field, and can optionally have ‘table_name’, ‘shape’, ‘unit’, and ‘dtype’ fields.</p></li>
<li><p><strong>header</strong> (<em>bool, optional</em>) Flag indicating whether to include the column names in the outputted table. Default value is False (no column names).</p></li>
<li><p><strong>float_format</strong> (<em>str, optional</em>) c-style formatting string for floating point values. Default value is ‘%.13f’.</p></li>
<li><p><strong>return_prop_info</strong> (<em>bool, optional</em>) Flag indicating if the filled-in prop_info is to be returned. Having this allows for 1:1 load/dump conversions. Default value is False (prop_info is not returned).</p></li>
<li><p><strong>extra</strong> (<em>dict, optional</em>) Allows extra per-atom data that is not part of the System to be included in the generated table. Useful when the per-atom data only has meaning in the tabular format and should not be added to System.</p></li>
</ul>
<p>Returns</p>
<ul class="simple">
<li><p>(<em>str</em>) The generated data table. Only returned if fp is None.</p></li>
</ul>
<p>Dump data without a header</p>
<div class="nbinput docutils container">
<div class="prompt highlight-none notranslate"><div class="highlight"><pre><span></span>[3]:
</pre></div>
</div>
<div class="input_area highlight-ipython3 notranslate"><div class="highlight"><pre>
<span></span><span class="n">table</span> <span class="o">=</span> <span class="n">system</span><span class="o">.</span><span class="n">dump</span><span class="p">(</span><span class="s1">&#39;table&#39;</span><span class="p">,</span> <span class="n">float_format</span><span class="o">=</span><span class="s1">&#39;</span><span class="si">%.5f</span><span class="s1">&#39;</span><span class="p">)</span>
<span class="nb">print</span><span class="p">(</span><span class="n">table</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="nboutput nblast docutils container">
<div class="prompt empty docutils container">
</div>
<div class="output_area docutils container">
<div class="highlight"><pre>
1 0.00000 0.00000 0.00000 1.00000 0.00000 0.00000 0.00000 0.00000 0.00000 0.00000 0.00000 0.00000 0.00000
2 1.60000 1.60000 1.60000 -1.00000 0.00000 0.00000 0.00000 0.00000 0.00000 0.00000 0.00000 0.00000 0.00000

</pre></div></div>
</div>
<p>Dump data with a header</p>
<div class="nbinput docutils container">
<div class="prompt highlight-none notranslate"><div class="highlight"><pre><span></span>[4]:
</pre></div>
</div>
<div class="input_area highlight-ipython3 notranslate"><div class="highlight"><pre>
<span></span><span class="n">table</span> <span class="o">=</span> <span class="n">system</span><span class="o">.</span><span class="n">dump</span><span class="p">(</span><span class="s1">&#39;table&#39;</span><span class="p">,</span> <span class="n">float_format</span><span class="o">=</span><span class="s1">&#39;</span><span class="si">%.5f</span><span class="s1">&#39;</span><span class="p">,</span> <span class="n">header</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="nb">print</span><span class="p">(</span><span class="n">table</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="nboutput nblast docutils container">
<div class="prompt empty docutils container">
</div>
<div class="output_area docutils container">
<div class="highlight"><pre>
atype pos[0] pos[1] pos[2] charge stress[0][0] stress[0][1] stress[0][2] stress[1][0] stress[1][1] stress[1][2] stress[2][0] stress[2][1] stress[2][2]
1 0.00000 0.00000 0.00000 1.00000 0.00000 0.00000 0.00000 0.00000 0.00000 0.00000 0.00000 0.00000 0.00000
2 1.60000 1.60000 1.60000 -1.00000 0.00000 0.00000 0.00000 0.00000 0.00000 0.00000 0.00000 0.00000 0.00000

</pre></div></div>
</div>
<p>Setting return_prop_info=True will also return a list of dictionaries that provides the transformation mapping between the table format and the scalar/vector/tensor per-atom properties.</p>
<div class="nbinput docutils container">
<div class="prompt highlight-none notranslate"><div class="highlight"><pre><span></span>[5]:
</pre></div>
</div>
<div class="input_area highlight-ipython3 notranslate"><div class="highlight"><pre>
<span></span><span class="n">table</span><span class="p">,</span> <span class="n">prop_info</span> <span class="o">=</span> <span class="n">system</span><span class="o">.</span><span class="n">dump</span><span class="p">(</span><span class="s1">&#39;table&#39;</span><span class="p">,</span> <span class="n">float_format</span><span class="o">=</span><span class="s1">&#39;</span><span class="si">%.5f</span><span class="s1">&#39;</span><span class="p">,</span> <span class="n">header</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">return_prop_info</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="nb">print</span><span class="p">(</span><span class="n">table</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="nboutput nblast docutils container">
<div class="prompt empty docutils container">
</div>
<div class="output_area docutils container">
<div class="highlight"><pre>
atype pos[0] pos[1] pos[2] charge stress[0][0] stress[0][1] stress[0][2] stress[1][0] stress[1][1] stress[1][2] stress[2][0] stress[2][1] stress[2][2]
1 0.00000 0.00000 0.00000 1.00000 0.00000 0.00000 0.00000 0.00000 0.00000 0.00000 0.00000 0.00000 0.00000
2 1.60000 1.60000 1.60000 -1.00000 0.00000 0.00000 0.00000 0.00000 0.00000 0.00000 0.00000 0.00000 0.00000

</pre></div></div>
</div>
<div class="nbinput docutils container">
<div class="prompt highlight-none notranslate"><div class="highlight"><pre><span></span>[6]:
</pre></div>
</div>
<div class="input_area highlight-ipython3 notranslate"><div class="highlight"><pre>
<span></span><span class="c1"># Show the generated prop_info conversion info</span>
<span class="k">for</span> <span class="n">pinfo</span> <span class="ow">in</span> <span class="n">prop_info</span><span class="p">:</span>
    <span class="nb">print</span><span class="p">(</span><span class="n">pinfo</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="nboutput nblast docutils container">
<div class="prompt empty docutils container">
</div>
<div class="output_area docutils container">
<div class="highlight"><pre>
{&#39;prop_name&#39;: &#39;atype&#39;, &#39;shape&#39;: (), &#39;table_name&#39;: [&#39;atype&#39;], &#39;unit&#39;: None, &#39;dtype&#39;: None}
{&#39;prop_name&#39;: &#39;pos&#39;, &#39;shape&#39;: (3,), &#39;table_name&#39;: [&#39;pos[0]&#39;, &#39;pos[1]&#39;, &#39;pos[2]&#39;], &#39;unit&#39;: None, &#39;dtype&#39;: None}
{&#39;prop_name&#39;: &#39;charge&#39;, &#39;shape&#39;: (), &#39;table_name&#39;: [&#39;charge&#39;], &#39;unit&#39;: None, &#39;dtype&#39;: None}
{&#39;prop_name&#39;: &#39;stress&#39;, &#39;shape&#39;: (3, 3), &#39;table_name&#39;: [&#39;stress[0][0]&#39;, &#39;stress[0][1]&#39;, &#39;stress[0][2]&#39;, &#39;stress[1][0]&#39;, &#39;stress[1][1]&#39;, &#39;stress[1][2]&#39;, &#39;stress[2][0]&#39;, &#39;stress[2][1]&#39;, &#39;stress[2][2]&#39;], &#39;unit&#39;: None, &#39;dtype&#39;: None}
</pre></div></div>
</div>
</div>
<div class="section" id="3.-atomman.load(‘table’)">
<h2>3. atomman.load(‘table’)<a class="headerlink" href="#3.-atomman.load(‘table’)" title="Permalink to this headline">¶</a></h2>
<p>Parameters</p>
<ul class="simple">
<li><p><strong>table</strong> (<em>str or file-like object</em>) The table content, file path or file-like object containing the content to read.</p></li>
<li><p><strong>box</strong> (<em>atomman.Box</em>) The atomic box to use when generating a System around the data.</p></li>
<li><p><strong>symbols</strong> (<em>tuple, optional</em>) Allows the list of element symbols to be assigned during loading.</p></li>
<li><p><strong>system</strong> (<em>atomman.System, optional</em>) The atomic system to load the values to. If not given, a new system will be constructed.</p></li>
<li><p><strong>prop_name</strong> (<em>list, optional</em>) The Atoms properties to generate. Must be given if prop_info is not.</p></li>
<li><p><strong>table_name</strong> (<em>list, optional</em>) The table column name(s) that correspond to each prop_name. If not given, the table_name values will be based on the prop_name values.</p></li>
<li><p><strong>shape</strong> (<em>list, optional</em>) The shape of each per-atom property. If not given, will be inferred from the length of each table_name value.</p></li>
<li><p><strong>unit</strong> (<em>list, optional</em>) Lists the units for each prop_name as stored in the table. For a value of None, no conversion will be performed for that property. For a value of ‘scaled’, the corresponding table values will be taken in box-scaled units. If not given, all unit values will be set to None (i.e. no conversions).</p></li>
<li><p><strong>dtype</strong> (<em>list, optional</em>) Allows for the data type of each property to be explicitly given. Values of None will infer the data type from the corresponding property values. If not given, all values will be None.</p></li>
<li><p><strong>prop_info</strong> (<em>list of dict, optional</em>) Structured form of property conversion parameters, in which each dictionary in the list corresponds to a single atoms property. Each dictionary must have a ‘prop_name’ field, and can optionally have ‘table_name’, ‘shape’, ‘unit’, and ‘dtype’ fields.</p></li>
<li><p><strong>skiprows</strong> (<em>int, optional</em>) Number of rows to skip before reading the data.</p></li>
<li><p><strong>usecols</strong> (<em>int, optional</em>) Which columns are to be used. Will be passed to pandas.read_csv() usecols option.</p></li>
<li><p><strong>nrows</strong> (<em>int, optional</em>) Number of rows of data to read.</p></li>
<li><p><strong>comment</strong> (<em>str, optional</em>) Specifies a character which indicates all text on a given line after is to be considered to be a comment and ignored by parser. This is often ‘#’.</p></li>
</ul>
<p>Returns</p>
<ul class="simple">
<li><p>(<em>atomman.System</em>) The generated system.</p></li>
</ul>
<p>atomman.load(‘table’) has a large number of parameters to allow many varieties of tabular data to be interpreted. Here, parameters are selected to read in the table generated above to reproduce the original system.</p>
<div class="nbinput docutils container">
<div class="prompt highlight-none notranslate"><div class="highlight"><pre><span></span>[7]:
</pre></div>
</div>
<div class="input_area highlight-ipython3 notranslate"><div class="highlight"><pre>
<span></span><span class="c1"># Show table and prop_info again</span>
<span class="nb">print</span><span class="p">(</span><span class="n">table</span><span class="p">)</span>
<span class="nb">print</span><span class="p">()</span>
<span class="nb">print</span><span class="p">(</span><span class="n">prop_info</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="nboutput nblast docutils container">
<div class="prompt empty docutils container">
</div>
<div class="output_area docutils container">
<div class="highlight"><pre>
atype pos[0] pos[1] pos[2] charge stress[0][0] stress[0][1] stress[0][2] stress[1][0] stress[1][1] stress[1][2] stress[2][0] stress[2][1] stress[2][2]
1 0.00000 0.00000 0.00000 1.00000 0.00000 0.00000 0.00000 0.00000 0.00000 0.00000 0.00000 0.00000 0.00000
2 1.60000 1.60000 1.60000 -1.00000 0.00000 0.00000 0.00000 0.00000 0.00000 0.00000 0.00000 0.00000 0.00000


[{&#39;prop_name&#39;: &#39;atype&#39;, &#39;shape&#39;: (), &#39;table_name&#39;: [&#39;atype&#39;], &#39;unit&#39;: None, &#39;dtype&#39;: None}, {&#39;prop_name&#39;: &#39;pos&#39;, &#39;shape&#39;: (3,), &#39;table_name&#39;: [&#39;pos[0]&#39;, &#39;pos[1]&#39;, &#39;pos[2]&#39;], &#39;unit&#39;: None, &#39;dtype&#39;: None}, {&#39;prop_name&#39;: &#39;charge&#39;, &#39;shape&#39;: (), &#39;table_name&#39;: [&#39;charge&#39;], &#39;unit&#39;: None, &#39;dtype&#39;: None}, {&#39;prop_name&#39;: &#39;stress&#39;, &#39;shape&#39;: (3, 3), &#39;table_name&#39;: [&#39;stress[0][0]&#39;, &#39;stress[0][1]&#39;, &#39;stress[0][2]&#39;, &#39;stress[1][0]&#39;, &#39;stress[1][1]&#39;, &#39;stress[1][2]&#39;, &#39;stress[2][0]&#39;, &#39;stress[2][1]&#39;, &#39;stress[2][2]&#39;], &#39;unit&#39;: None, &#39;dtype&#39;: None}]
</pre></div></div>
</div>
<div class="nbinput docutils container">
<div class="prompt highlight-none notranslate"><div class="highlight"><pre><span></span>[8]:
</pre></div>
</div>
<div class="input_area highlight-ipython3 notranslate"><div class="highlight"><pre>
<span></span><span class="c1"># Pass table with box and prop_info</span>
<span class="n">table_system</span> <span class="o">=</span> <span class="n">am</span><span class="o">.</span><span class="n">load</span><span class="p">(</span><span class="s1">&#39;table&#39;</span><span class="p">,</span> <span class="n">table</span><span class="p">,</span> <span class="n">box</span><span class="o">=</span><span class="n">system</span><span class="o">.</span><span class="n">box</span><span class="p">,</span> <span class="n">symbols</span><span class="o">=</span><span class="p">[</span><span class="s1">&#39;Cs&#39;</span><span class="p">,</span> <span class="s1">&#39;Cl&#39;</span><span class="p">],</span>
                       <span class="n">skiprows</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">prop_info</span><span class="o">=</span><span class="n">prop_info</span><span class="p">)</span>

<span class="nb">print</span><span class="p">(</span><span class="n">table_system</span><span class="p">)</span>
<span class="n">table_system</span><span class="o">.</span><span class="n">atoms_df</span><span class="p">()</span>
</pre></div>
</div>
</div>
<div class="nboutput docutils container">
<div class="prompt empty docutils container">
</div>
<div class="output_area docutils container">
<div class="highlight"><pre>
avect =  [ 3.200,  0.000,  0.000]
bvect =  [ 0.000,  3.200,  0.000]
cvect =  [ 0.000,  0.000,  3.200]
origin = [ 0.000,  0.000,  0.000]
natoms = 2
natypes = 2
symbols = (&#39;Cs&#39;, &#39;Cl&#39;)
pbc = [ True  True  True]
per-atom properties = [&#39;atype&#39;, &#39;pos&#39;, &#39;charge&#39;, &#39;stress&#39;]
     id |   atype |  pos[0] |  pos[1] |  pos[2]
      0 |       1 |   0.000 |   0.000 |   0.000
      1 |       2 |   1.600 |   1.600 |   1.600
</pre></div></div>
</div>
<div class="nboutput nblast docutils container">
<div class="prompt highlight-none notranslate"><div class="highlight"><pre><span></span>[8]:
</pre></div>
</div>
<div class="output_area rendered_html docutils container">
<div>
<style scoped>
    .dataframe tbody tr th:only-of-type {
        vertical-align: middle;
    }

    .dataframe tbody tr th {
        vertical-align: top;
    }

    .dataframe thead th {
        text-align: right;
    }
</style>
<table border="1" class="dataframe">
  <thead>
    <tr style="text-align: right;">
      <th></th>
      <th>atype</th>
      <th>pos[0]</th>
      <th>pos[1]</th>
      <th>pos[2]</th>
      <th>charge</th>
      <th>stress[0][0]</th>
      <th>stress[0][1]</th>
      <th>stress[0][2]</th>
      <th>stress[1][0]</th>
      <th>stress[1][1]</th>
      <th>stress[1][2]</th>
      <th>stress[2][0]</th>
      <th>stress[2][1]</th>
      <th>stress[2][2]</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>0</td>
      <td>1</td>
      <td>0.0</td>
      <td>0.0</td>
      <td>0.0</td>
      <td>1.0</td>
      <td>0.0</td>
      <td>0.0</td>
      <td>0.0</td>
      <td>0.0</td>
      <td>0.0</td>
      <td>0.0</td>
      <td>0.0</td>
      <td>0.0</td>
      <td>0.0</td>
    </tr>
    <tr>
      <td>1</td>
      <td>2</td>
      <td>1.6</td>
      <td>1.6</td>
      <td>1.6</td>
      <td>-1.0</td>
      <td>0.0</td>
      <td>0.0</td>
      <td>0.0</td>
      <td>0.0</td>
      <td>0.0</td>
      <td>0.0</td>
      <td>0.0</td>
      <td>0.0</td>
      <td>0.0</td>
    </tr>
  </tbody>
</table>
</div></div>
</div>
<div class="nbinput docutils container">
<div class="prompt highlight-none notranslate"><div class="highlight"><pre><span></span>[9]:
</pre></div>
</div>
<div class="input_area highlight-ipython3 notranslate"><div class="highlight"><pre>
<span></span><span class="c1"># Using the generated prop_info from dump makes the resulting properties have the right shape.</span>
<span class="nb">print</span><span class="p">(</span><span class="n">table_system</span><span class="o">.</span><span class="n">atoms</span><span class="o">.</span><span class="n">stress</span><span class="p">[</span><span class="mi">0</span><span class="p">])</span>
</pre></div>
</div>
</div>
<div class="nboutput nblast docutils container">
<div class="prompt empty docutils container">
</div>
<div class="output_area docutils container">
<div class="highlight"><pre>
[[0. 0. 0.]
 [0. 0. 0.]
 [0. 0. 0.]]
</pre></div></div>
</div>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
  <h3><a href="../index.html">Table of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">Introduction to atomman: table conversions</a><ul>
<li><a class="reference internal" href="#1.-Introduction">1. Introduction</a></li>
<li><a class="reference internal" href="#2.-System.dump(‘table’)">2. System.dump(‘table’)</a></li>
<li><a class="reference internal" href="#3.-atomman.load(‘table’)">3. atomman.load(‘table’)</a></li>
</ul>
</li>
</ul>

  <h4>Previous topic</h4>
  <p class="topless"><a href="1.4.3._CIF_conversions.html"
                        title="previous chapter">Introduction to atomman: CIF conversions</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="1.4.5._LAMMPS_data_file_conversions.html"
                        title="next chapter">Introduction to atomman: LAMMPS data file conversions</a></p>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="../genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="../py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="1.4.5._LAMMPS_data_file_conversions.html" title="Introduction to atomman: LAMMPS data file conversions"
             >next</a> |</li>
        <li class="right" >
          <a href="1.4.3._CIF_conversions.html" title="Introduction to atomman: CIF conversions"
             >previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="../index.html">atomman 1.4.0 documentation</a> &#187;</li>
          <li class="nav-item nav-item-1"><a href="index.html" >Tutorials</a> &#187;</li> 
      </ul>
    </div>
    <div class="footer" role="contentinfo">
      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 2.2.0.
    </div>
  </body>
</html>